|
|
PixelToChar |
||||
| Header: | QuickdrawText.h | Carbon status: | Supported | |
Returns the byte offset of a character in a style run, or part of a style run, whose onscreen glyph is nearest the place where the user clicked the mouse.
SInt16 PixelToChar (
Ptr textBuf,
SInt32 textLength,
Fixed slop,
Fixed pixelWidth,
Boolean *leadingEdge,
Fixed *widthRemaining,
JustStyleCode styleRunPosition,
Point numer,
Point denom
);
A pointer to the start of the text segment.
The length in bytes of the entire text segment pointed to by textBuf. The PixelToChar function requires the context of the complete text segment in order to determine the correct value.
The amount of slop for the text to be drawn. A positive value extends the text segment; a negative value condenses the text segment.
The value of this parameter is the number of pixels by which the width of the text segment is to be changed, after the text has been scaled. The slop is a signed value that specifies how much the text is to be extended or condensed. The slop is derived from the calculations made using the proportion returned from the PortionLine function for a style run. To measure or draw text that is not to be extended or condensed, pass a slop value of 0.
The screen location of the glyph associated with the character whose byte offset is to be returned. The screen location is measured in pixels beginning from the left edge of the text segment for which you call PixelToChar.
Pointer to a Boolean flag that, upon completion of the call, is set to TRUE if the pixel location is on the leading edge of the glyph, and FALSE if the pixel location is on the trailing edge of the glyph. The leading edge is the left side if the direction of the character that the glyph represents is left-to-right (such as a Roman character), and the right side if the character direction is right-to-left (such as an Arabic or a Hebrew letter).
Pointer to a location that, upon completion of the call, contains –1 if the pixel location (specified by the pixelWidth parameter) falls within the style run (represented by the textLen bytes starting at textBuf). Otherwise, the location contains the amount of pixels by which the input pixel location (pixelWidth) extends beyond the right edge of the text for which you called PixelToChar.
The position on the line of this style run. The style run can be the only one on the line, the leftmost on the line, the rightmost on the line, or one between two other style runs.
This parameter specifies the position of the style run on the display line. It is used to determine the proportion of total slop to apply to a style run, measure or draw a line of justified text, identify where to break a line of text, and determine the caret position to mark an insertion point or highlight text.
The style run position parameter is meaningful only for those script systems that use intercharacter spacing for justification. For all other script systems, the parameter exists for future extensibility. Although the style run position parameter is not used, for example, for justifying text in the Roman script system, to allow for future compatibility, you should always specify the appropriate value for it for all calls that take it.
For those script systems that do use intercharacter spacing, space between style runs may be allocated differently depending upon whether the style run is leftmost, rightmost, or between two other style runs. For example, depending on the script system, if a style run occurs at the beginning or end of a line, extra space may not be added to the outer edge of the outermost glyph, whereas if a style run is interior to a line, all of the glyphs of the text may be treated the same: extra space is allocated to both sides of every glyph including those at either end of the style run.
The current implementations of simple script systems such as Roman and Cyrillic do not justify a line of text by changing the width of nonspace characters. Instead, they rely solely on the use of space characters: the same amount of extra width is added to (or subtracted from) every space whether the space is at the beginning or end of the line or interior to it.
A point giving the numerator for the horizontal and vertical scaling factors.
Both numer and denom are point values: numer specifies the numerator for the horizontal and vertical scaling factors, and denom specifies the denominator for the horizontal and vertical scaling factors. Together, these values specify the scaling factors for the text: numer.v over denom.v gives the vertical scaling (height), and numer.h over denom.h gives the horizontal scaling factors (width). You need to specify values for numer and denom even if you are not scaling the text. For unscaled text, you can specify scaling factors of 1, 1.
A point giving the denominator for the horizontal and vertical scaling factors.
The byte offset of a character in a style run, or part of a style run, whose onscreen glyph is nearest the place where the user clicked the mouse.
You can use the information that PixelToChar returns for highlighting, word selection, and identifying the caret position. The PixelToChar function returns a byte offset and a Boolean value that describes whether the pixel location is on the leading edge or trailing edge of the glyph where the mouse-down event occurred. When the pixel location falls on a glyph that corresponds to one or more characters that are part of the text segment, the PixelToChar function uses the direction of the character or characters to determine which side of the glyph is the leading edge. (A glyph can represent more than one character, for example, for a ligature. Generally, if a glyph represents more than one character, all of the characters have the same text direction.)
If the pixel location is on the leading edge, PixelToChar returns the byte offset of the character whose glyph is at the pixel location. (If the glyph represents multiple characters, it returns the byte offset of the first of these characters in memory.) If the pixel location is on the trailing edge, PixelToChar returns the byte offset of the first character in memory following the character or characters represented by the glyph. If the pixel location is on the trailing edge of the glyph that corresponds to the last character in the text segment, PixelToChar returns a byte offset equal to the length of the text segment.
When the pixel location is before the leading edge of the first glyph in the displayed text segment, PixelToChar returns a leading edge value of FALSE and the byte offset of the first character. When the pixel location is after the trailing edge of the last glyph in the displayed text segment, PixelToChar returns a leading edge value of TRUE and the next byte offset in memory, the one after the last character in the text segment. If the primary line direction is left to right, before means to the left of all of the glyphs for the characters in the text segment, and after means to the right of all these glyphs. If the primary line direction is right to left, before and after hold the opposite meanings.
You also use the value of the leadingEdge flag to help determine the value of the direction parameter to pass to CharToPixel, which you call to get the caret position. If the leadingEdge flag is FALSE, you base the value of the direction parameter on the direction of the character at the byte offset in memory that precedes the one that PixelToChar returns; if leadingEdge is TRUE, you base the value of the direction parameter on the direction of the character at the byte offset that PixelToChar returns. If there isn’t a character at the byte offset, you base the value of the direction parameter on the primary line direction as determined by the SysDirection global variable.
You specify a value for textLen that is equal to the entire visible part of the style run on a line and includes trailing spaces if and only if they are displayed. They may not be displayed, for example, for the last style run in memory order that is part of the current line.
Be sure to pass the same values for styleRunPosition and the scaling factors (numer and denom) to PixelToChar that you pass to any of the other justification functions for this style run.
You pass PixelToChar a pointer to the byte offset of the character in the text buffer that begins the text segment or style run containing the character whose glyph is at the pixel location. If you do not know which style run on the display line contains the character whose glyph is at the pixel location, you can loop through the style runs until you find the one that contains the pixel location. If the style run contains the character, PixelToChar returns its byte offset. If it doesn’t, you can use the widthRemaining parameter value to help determine which style run contains the glyph at the pixel location.
If you pass PixelToChar the pixel width of the display line, you can use the returned value of widthRemaining to calculate the length of a style run. The widthRemaining parameter contains the length in pixels from the end of the style run for which you call PixelToChar to the end of the display line, in this case, if the style run for which you call it does not include the byte offset whose glyph corresponds to the pixel location. You subtract the returned widthRemaining value from the screen pixel width of the display line to get the style run’s length.
To truncate a line of text, you can use PixelToChar to find the byte offset of the character where the line should be broken. To return the correct byte offset associated with the pixel location of a mouse-down event when the text belongs to a right-to-left script system, the PixelToChar function reorders the text. If right-to-left text is reordered when you use PixelToChar to determine where to break a line, it returns the wrong byte offset. To get the correct result, you must turn off reordering before you call PixelToChar. Remember to restore reordering after you have determined where to break the line.
The PixelToChar function works with text in all script systems, and for text that is justified or not. For contextual script systems, PixelToChar takes into account the widths of any ligatures, reversals, and compound characters that were created when the text was drawn.
Because 2-byte script systems also include characters consisting of only one byte, you should not simply multiply the number of characters by 2 to determine this value; you must determine and specify the correct number of bytes.
The PixelToChar function may move memory; do not call this function at interrupt time.
Supported in Carbon. Available in Carbon 1.0.2 and later when running Mac OS 8.1 or later.
© 2000 Apple Computer, Inc. (Last Updated 6/30/2000)